feat: add billing foundation and entitlement enforcement

- add workspace-scoped billing storage, usage tracking, and add-on catalog
- enforce plan entitlements for search and deep research routes
- expand pricing and account UI around billing state, usage, and upgrades

WORKSPACE-READINESS.md

@@ -0,0 +1,91 @@
+# Workspace Readiness
+
+## Current State
+
+LocaleScope now uses workspaces as the billing and quota subject, but the core research domain is still mostly user-owned.
+
+Already workspace-scoped:
+- workspaces
+- workspace memberships
+- billing accounts
+- usage periods and counters
+- add-on purchases and balances
+
+Still user-scoped but targeted for workspace ownership:
+- search jobs
+- deep research batches
+- saved businesses
+- search job results
+
+Should remain user-scoped:
+- users
+- sessions
+
+## Practical Implication
+
+The product currently operates in a mixed phase:
+- billing, quotas, and memberships are workspace-based
+- most saved operational data still behaves like personal user-owned data
+
+This means some commercial promises can be enforced now, while others should remain soft-gated or clearly phased.
+
+## Enforceability Matrix
+
+Hard enforce now:
+- research credits
+
+Requires backend route before hard enforcement:
+- exports
+
+Soft gate now:
+- users included
+- workspace limits
+
+Requires schema migration first:
+- shared assets / shared history
+- collaboration permissions
+- tagging and notes
+- shared lists
+
+Future implementation:
+- saved searches
+- deduplication
+- export history
+- scheduled research
+- CRM integrations
+- API access
+- webhooks
+- enrichments
+
+## Collaboration Phases
+
+### V1: Personal Data With Workspace Billing
+- a user consumes usage against their primary workspace
+- billing and quotas are tracked at the workspace level
+- search history and saved businesses remain effectively personal
+
+### V2: Shared Workspace Data
+- search jobs and deep research batches become workspace-owned
+- saved businesses and results become shareable across members
+- role-aware collaboration and shared asset rules become enforceable
+
+## Migration Target
+
+Before team/workspace promises are enforced as real collaboration features, these tables should gain `workspace_id` ownership:
+- `search_jobs`
+- `deep_research_batches`
+- `businesses`
+- `search_job_results`
+
+Recommended migration approach:
+1. add nullable `workspace_id`
+2. backfill from each user's primary workspace
+3. update repositories/services to prefer workspace ownership
+4. make `workspace_id` non-null once the transition is complete
+
+## Rule To Keep In Mind
+
+Until workspace-owned domain data exists, team and collaboration plan promises should be treated as:
+- commercially described
+- softly gated in product messaging
+- not fully enforceable runtime collaboration behavior