feat: launch Stripe billing flows with lifecycle hardening and analytics

add Stripe checkout, portal, webhook ingestion, and idempotent event persistence

add billing lifecycle state (grace/sync/timeline/admin visibility) and stronger entitlement handling

add analytics event tracking and admin summary APIs plus account/pricing UI integration

README.md

@@ -18,6 +18,7 @@ LocaleScope is a React + Vite app for researching local markets, saving business
    - `DATABASE_URL`
    - `COOKIE_SECRET`
    - `GOOGLE_MAPS_SERVER_KEY`
+   - Stripe env vars below if you want to test billing locally
 3. Run the frontend:
    `npm run dev:web`
 
@@ -35,6 +36,34 @@ If you open the app from another machine on your LAN, set `VITE_API_BASE_URL` an
 4. Start the worker:
    `npm run dev:worker`
 
+## Stripe Billing Setup
+
+Stripe is now the active payments integration for self-serve subscriptions and one-time export packs.
+
+Configure these server-side env vars to enable billing routes:
+
+- `STRIPE_SECRET_KEY`
+- `STRIPE_WEBHOOK_SECRET`
+- `STRIPE_PRICE_STARTER_MONTHLY`
+- `STRIPE_PRICE_STARTER_ANNUAL`
+- `STRIPE_PRICE_GROWTH_MONTHLY`
+- `STRIPE_PRICE_GROWTH_ANNUAL`
+- `STRIPE_PRICE_PRO_MONTHLY`
+- `STRIPE_PRICE_PRO_ANNUAL`
+- `STRIPE_PRICE_EXPORT_PACK_10K`
+- `STRIPE_PRICE_EXPORT_PACK_50K`
+- `STRIPE_BILLING_PORTAL_CONFIGURATION_ID` optional
+- `BILLING_ADMIN_EMAILS` optional comma-separated allowlist for internal billing admin access
+
+Notes:
+
+- The internal catalog in `shared/billing/plans.ts` and `shared/billing/addons.ts` remains canonical. Stripe price IDs are environment-specific mappings only.
+- Apply migrations before testing Stripe webhooks so `billing_webhook_events` exists: `npm run migrate`
+- Enterprise stays on a manual sales/invoicing path and does not use self-serve checkout.
+- Stripe lifecycle hardening now treats `past_due` subscriptions as a grace-window state before chargeable actions hard-block. The default grace window is 7 days.
+- Billing return notices now appear on the account page for completed and canceled checkout flows.
+- Internal billing support visibility is available through `/api/admin/billing/workspaces` for allowlisted admin emails.
+
 ## Docker Deployment
 
 1. Copy `.env.example` to `.env` and set at least: