feat(auth): auto-create admin user profiles with highest tier and complimentary flag

- Add `is_complimentary` column to UserProfile model (migration 019)
- Update `_ensure_user_profile` to accept `is_admin` param; admins get
  highest subscription tier, is_complimentary=True, onboarding skipped
- Call `_ensure_user_profile` from all login paths (OAuth, local user, admin creds)
- Add `is_complimentary` to UserProfileUpsert schema, response helpers,
  list_users, get_user, upsert_user_profile in admin API
- Add complimentary toggle to admin users UI with gift badge in table
- Write 18 new tests covering complimentary plan and admin auto-creation
- Update SubscriptionTiers.md documentation

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

app/api/admin_users.py

@@ -59,6 +59,11 @@ class UserProfileUpsert(BaseModel):
     subscription_billing_cycle: str = Field(default="monthly", pattern="^(monthly|yearly)$")
     subscription_period_start: datetime | None = None
     allow_overage: bool = False
+    is_complimentary: bool = Field(
+        default=False,
+        description="When True the user is on a complimentary (uncharged) plan — they keep all tier "
+        "quota benefits but are never billed via Stripe.",
+    )
 
 
 class UserProfileResponse(BaseModel):
@@ -74,6 +79,7 @@ class UserProfileResponse(BaseModel):
     subscription_billing_cycle: str
     subscription_period_start: str | None
     allow_overage: bool
+    is_complimentary: bool
     created_at: str | None
     updated_at: str | None
 
@@ -92,6 +98,7 @@ class UserSummary(BaseModel):
     subscription_billing_cycle: str | None
     subscription_period_start: str | None
     allow_overage: bool
+    is_complimentary: bool
     profile_id: int | None
     document_count: int
     last_upload: str | None
@@ -121,6 +128,7 @@ def _profile_to_dict(profile: UserProfile) -> dict[str, Any]:
         if profile.subscription_period_start
         else None,
         "allow_overage": bool(profile.allow_overage),
+        "is_complimentary": bool(profile.is_complimentary),
         "created_at": profile.created_at.isoformat() if profile.created_at else None,
         "updated_at": profile.updated_at.isoformat() if profile.updated_at else None,
     }
@@ -194,6 +202,7 @@ def list_users(
                 if (profile and profile.subscription_period_start)
                 else None,
                 "allow_overage": bool(profile.allow_overage) if profile else False,
+                "is_complimentary": bool(profile.is_complimentary) if profile else False,
                 "profile_id": profile.id if profile else None,
                 "document_count": doc_row.doc_count if doc_row else 0,
                 "last_upload": doc_row.last_upload.isoformat() if (doc_row and doc_row.last_upload) else None,
@@ -235,6 +244,7 @@ def get_user(user_id: str, db: DbSession, _admin: AdminUser) -> dict[str, Any]:
         if (profile and profile.subscription_period_start)
         else None,
         "allow_overage": bool(profile.allow_overage) if profile else False,
+        "is_complimentary": bool(profile.is_complimentary) if profile else False,
         "profile_id": profile.id if profile else None,
         "document_count": doc_count,
         "last_upload": last_upload,
@@ -265,6 +275,7 @@ def upsert_user_profile(
     profile.subscription_billing_cycle = body.subscription_billing_cycle
     profile.subscription_period_start = body.subscription_period_start
     profile.allow_overage = body.allow_overage
+    profile.is_complimentary = body.is_complimentary
     if body.subscription_tier is not None:
         from app.utils.subscription import TIERS