chore: Update backend services, intelligence integration, and documentation

docs/subscription/Billing_and_Usage.md

@@ -0,0 +1,71 @@
+# Subscription, Billing & Usage Tracking
+
+This document details how ALwrity manages subscriptions, processes payments via Stripe, and tracks granular usage for every user interaction.
+
+## 1. Subscription Model
+
+ALwrity uses a **tier-based subscription model** enforced at the API gateway level.
+
+### Tiers
+- **Free**: Limited access, community support.
+- **Basic**: Entry-level AI usage, standard support.
+- **Pro**: High limits, advanced models (Gemini Pro, FLUX), priority support.
+- **Enterprise**: Custom limits, dedicated infrastructure.
+
+### Data Model (`UserSubscription`)
+Stored in the user's SQLite database (`alwrity_user_{id}.db`):
+- `stripe_customer_id`: Link to Stripe Customer.
+- `stripe_subscription_id`: Active subscription ID.
+- `plan_id`: Internal plan reference (linked to `SubscriptionPlan`).
+- `status`: `active`, `past_due`, `canceled`, etc.
+- `current_period_start` / `end`: Defines the billing cycle window.
+
+## 2. Billing Integration (Stripe)
+
+We use **Stripe** for all payments, webhooks, and portal management.
+
+### Key Components
+- **StripeService**: Handles checkout creation, portal sessions, and webhooks.
+- **Webhooks**: Listens for events like `invoice.payment_succeeded`, `customer.subscription.updated`.
+  - **Idempotency**: All webhooks are tracked in `ProcessedStripeEvent` to prevent duplicate processing.
+  - **Reliability**: Events are processed transactionally; failures are logged and retried by Stripe.
+- **Configuration**: Plan-to-Price mapping is loaded from environment variables (`STRIPE_PLAN_PRICE_MAPPING_TEST` / `_LIVE`) to ensure sync between code and Stripe Dashboard.
+
+### Checkout Flow
+1. Frontend calls `/api/subscription/create-checkout-session`.
+2. Backend validates user and creates Stripe Session.
+3. User pays on Stripe.
+4. Stripe sends `checkout.session.completed` webhook.
+5. Backend provisions subscription and credits in `UserSubscription`.
+
+## 3. Usage Tracking
+
+Every API call to an LLM provider is tracked, costed, and logged.
+
+### Tracking Flow
+1. **Pre-flight Check** (`check_usage_limits`):
+   - Before generating content, the system estimates cost/tokens.
+   - If user exceeds plan limits (e.g., "50 videos/month"), the request is rejected (429).
+2. **Execution**: The provider generates the content.
+3. **Post-execution Log** (`track_usage`):
+   - Actual tokens/duration are measured.
+   - Cost is calculated based on `APIProviderPricing` table.
+   - Entry added to `APIUsageLog` (granular) and aggregated into `UsageSummary` (monthly totals).
+
+### Database Tables
+- **`APIUsageLog`**: Immutable ledger of every call.
+  - Fields: `user_id`, `provider`, `model`, `input_tokens`, `output_tokens`, `cost`, `status_code`.
+- **`UsageSummary`**: Aggregated stats per billing period.
+  - Fields: `total_calls`, `total_cost`, `gemini_calls`, `video_calls`, etc.
+  - **Unique Constraint**: Enforced on `(user_id, billing_period)` to prevent data drift.
+
+### Pricing Engine (`PricingService`)
+- Costs are not hardcoded. They are fetched from `APIProviderPricing` table.
+- Supports per-token (text), per-image (media), and per-second (video/audio) pricing models.
+- Admin can update pricing in DB without redeploying code.
+
+## 4. Frontend Integration
+
+- **Usage Dashboard**: Visualizes consumption vs. limits.
+- **Real-time**: Usage stats are typically updated immediately after generation.
+- **Limit Rings**: UI components show percentage used (e.g., "80% of monthly video limit").