Implement Premium Entitlements and Feature Gating System

[Copilot]

This PR implements a comprehensive premium entitlements system that gates advanced features behind premium purchases, with full integration for Play Billing (Android) and StoreKit (iOS).

Key Features

🔐 Core Entitlement System

• EntitlementService: Manages premium status with local persistence and real-time billing integration
• BillingService: Handles Play Billing/StoreKit for purchases, subscriptions, and restoration
• Feature-based gating: Granular control over individual premium features

🎨 UI Components

• FeatureGate: Contextual premium feature gating with non-intrusive upsell prompts
• SimpleFeatureGate: Overlay-based feature locking for visual elements
• PremiumButton: Smart buttons that show upgrade dialogs for non-premium users
• UpsellDialog: Beautiful upgrade prompts with feature benefits and gradients

⭐ Premium Features Gated

• Voice note transcription and unlimited recordings
• Advanced drawing tools with layers support
• Premium export formats (PDF, Word)
• Background recording capabilities
• Cloud sync functionality
• Ad-free experience

Implementation Highlights

Real Integration Examples

The system is already integrated into existing screens:

// Note editor with gated OCR functionality
Consumer<EntitlementService>(
  builder: (context, entitlementService, _) {
    final hasOcrAccess = entitlementService.hasFeature(PremiumFeature.voiceTranscription);
    return FloatingActionButton(
      onPressed: hasOcrAccess 
        ? () => showOcrDialog()
        : () => showPremiumDialog(PremiumFeature.voiceTranscription),
      // Visual feedback with lock overlay for non-premium users
    );
  },
)

// Export menu with premium PDF option
FeatureGate(
  feature: PremiumFeature.exportFormats,
  child: ListTile(title: Text('Export as PDF'), onTap: exportAsPdf),
  fallback: ListTile(
    title: Row(children: [Text('Export as PDF'), Icon(Icons.star)]),
    subtitle: Text('Premium feature'),
    onTap: () => showPremiumDialog(PremiumFeature.exportFormats),
  ),
)

🧪 Comprehensive Testing

• 13 passing tests for EntitlementService covering all functionality
• Widget tests for premium UI components
• Mock billing service integration for development
• Debug mode bypass for testing premium features

🛡️ Security & Quality

• Purchase verification with proper error handling
• Local storage persistence with billing service validation
• Graceful fallbacks for network/billing failures
• Clean architecture with zero analysis issues in premium code

📱 Developer Experience

• Debug mode: All premium features available during development
• Manual controls: Grant/revoke premium access for testing
• Comprehensive documentation: Complete usage guide with examples
• Example screen: Interactive demo showing all premium features

Usage Examples

// Simple feature gating
FeatureGate(
  feature: PremiumFeature.advancedDrawingTools,
  child: AdvancedToolsWidget(),
  showUpsell: true, // Shows contextual upgrade prompt
)

// Premium-aware button
PremiumButton(
  feature: PremiumFeature.exportFormats,
  onPressed: () => exportToPDF(),
  child: Row(children: [Icon(Icons.picture_as_pdf), Text('Export as PDF')]),
)

// Manual premium check
if (entitlementService.hasFeature(PremiumFeature.cloudSync)) {
  // Show sync options
} else {
  // Show upgrade prompt
}

The system provides a smooth, non-intrusive experience where free users see gentle upgrade prompts instead of locked-out features, while premium users get full access to advanced functionality.

Files Added/Modified

New Core Services:

• lib/services/entitlements/entitlement_service.dart - Premium status management
• lib/services/billing/billing_service.dart - In-app purchase handling

New UI Components:

• lib/widgets/premium/feature_gate.dart - Feature gating widgets
• lib/widgets/premium/upsell_dialog.dart - Upgrade dialogs

Integration Examples:

• lib/examples/premium_feature_example.dart - Complete demo screen
• PREMIUM_ENTITLEMENTS.md - Comprehensive documentation

Updated Integrations:

• lib/presentation/note_creation_editor/note_creation_editor.dart - Real feature gating
• lib/presentation/premium_upgrade/premium_upgrade.dart - Billing integration
• lib/main.dart - Service initialization and providers

Fixes #23.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.