feat: RBAC Phase 1 — consolidate user roles into 4-value enum

Consolidate User.role (2-value: admin/store) + User.is_super_admin (boolean)
into a single 4-value UserRole enum: super_admin, platform_admin,
merchant_owner, store_member. Drop stale StoreUser.user_type column.
Fix role="user" bug in merchant creation.

Key changes:
- Expand UserRole enum from 2 to 4 values with computed properties
  (is_admin, is_super_admin, is_platform_admin, is_merchant_owner, is_store_user)
- Add Alembic migration (tenancy_003) for data migration + column drops
- Remove is_super_admin from JWT token payload
- Update all auth dependencies, services, routes, templates, JS, and tests
- Update all RBAC documentation

66 files changed, 1219 unit tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/architecture/user-context-pattern.md

@@ -35,18 +35,20 @@ from app.modules.tenancy.models import User  # noqa: API-007 violation
 id: int                 # User ID
 email: str              # Email address
 username: str           # Username
-role: str               # "admin" or "store"
+role: str               # "super_admin", "platform_admin", "merchant_owner", or "store_member"
 is_active: bool         # Account status
 ```
 
 ### Admin-Specific Fields
 ```python
-is_super_admin: bool                      # True for super admins
+is_super_admin: bool                      # Computed: role == "super_admin" (not stored in DB or JWT)
 accessible_platform_ids: list[int] | None # Platform IDs (None = all for super admin)
 token_platform_id: int | None             # Selected platform from JWT
 token_platform_code: str | None           # Selected platform code from JWT
 ```
 
+**Note**: `is_super_admin` is no longer a database column or JWT claim. It is derived from `role == "super_admin"`. On the `User` model it is a computed property; on `UserContext` it is populated from the role field during `from_user()` construction.
+
 ### Store-Specific Fields
 ```python
 token_store_id: int | None    # Store ID from JWT
@@ -80,7 +82,9 @@ preferred_language: str | None
 ```
 1. POST /api/v1/admin/auth/login
    - Returns LoginResponse with user data and token
-   - Token includes: user_id, role, is_super_admin, accessible_platforms
+   - Token includes: user_id, role (e.g. "super_admin" or "platform_admin"),
+     accessible_platforms
+   - Note: is_super_admin is NOT in the JWT; derive from role == "super_admin"
 
 2. GET /api/v1/admin/auth/accessible-platforms
    - Returns list of platforms admin can access
@@ -93,29 +97,30 @@ preferred_language: str | None
 4. Subsequent API calls
    - Token decoded → UserContext populated
    - current_user.token_platform_id available
+   - current_user.is_super_admin derived from role
 ```
 
 ### JWT Token → UserContext Mapping
 
 When a JWT token is decoded, these fields are mapped:
 
-| JWT Claim | UserContext Field |
-|-----------|-------------------|
-| `sub` | `id` |
-| `username` | `username` |
-| `email` | `email` |
-| `role` | `role` |
-| `is_super_admin` | `is_super_admin` |
-| `accessible_platforms` | `accessible_platform_ids` |
-| `platform_id` | `token_platform_id` |
-| `platform_code` | `token_platform_code` |
-| `store_id` | `token_store_id` |
-| `store_code` | `token_store_code` |
-| `store_role` | `token_store_role` |
+| JWT Claim | UserContext Field | Notes |
+|-----------|-------------------|-------|
+| `sub` | `id` | |
+| `username` | `username` | |
+| `email` | `email` | |
+| `role` | `role` | 4-value enum: `super_admin`, `platform_admin`, `merchant_owner`, `store_member` |
+| *(derived from role)* | `is_super_admin` | Computed: `role == "super_admin"` (no longer a JWT claim) |
+| `accessible_platforms` | `accessible_platform_ids` | |
+| `platform_id` | `token_platform_id` | |
+| `platform_code` | `token_platform_code` | |
+| `store_id` | `token_store_id` | |
+| `store_code` | `token_store_code` | |
+| `store_role` | `token_store_role` | |
 
 ## Helper Methods
 
-`UserContext` provides helper methods:
+`UserContext` provides helper methods and computed properties:
 
 ```python
 # Check platform access
@@ -127,10 +132,16 @@ platform_ids = current_user.get_accessible_platform_ids()
 # Returns None for super admins (all platforms)
 # Returns list[int] for platform admins
 
-# Check role
-if current_user.is_admin:
+# Check role categories (computed from role field)
+if current_user.is_admin:           # role in ("super_admin", "platform_admin")
     ...
-if current_user.is_store:
+if current_user.is_super_admin:     # role == "super_admin"
+    ...
+if current_user.is_platform_admin:  # role == "platform_admin"
+    ...
+if current_user.is_merchant_owner:  # role == "merchant_owner"
+    ...
+if current_user.is_store_user:      # role in ("merchant_owner", "store_member")
     ...
 
 # Full name