feat: update user roles and passwords in QA driver, enhance documentation with error codes, and improve trial activation error handling

src/ClinicService/Controller/ClinicServiceController.php

@@ -219,6 +219,14 @@ class ClinicServiceController extends BaseController
     {
         [$entityType, $entityId] = $this->resolveEntity($user);
 
+        // A user with neither a doctor profile nor a clinic (admin, secretary,
+        // representation, plain patient) resolves to EntityContext::unknown(),
+        // whose id is null — findByEntity() declares int and fataled with a 500.
+        // Same condition, same answer as assertServicesGate(): forbidden.
+        if ($entityId === null) {
+            throw new AppException(ErrorCodes::ERR_FORBIDDEN_001, null, 403);
+        }
+
         return $this->success($this->serializeItems(
             $this->itemRepo->findByEntity($entityType, $entityId)
         ));

src/Subscription/Service/SubscriptionService.php

@@ -71,9 +71,12 @@ class SubscriptionService
             throw new AppException(ErrorCodes::ERR_NOT_FOUND_001, null, 500);
         }
 
+        // Deactivating the trial period is a normal admin configuration, not a
+        // broken install — surface it as "trial disabled", the same 422 the
+        // trial_enabled flag produces, rather than a 500.
         $trialPeriod = $this->periodRepo->findTrialPeriodForPlan($basicPlan);
         if ($trialPeriod === null) {
-            throw new AppException(ErrorCodes::ERR_NOT_FOUND_001, null, 500);
+            throw new AppException(ErrorCodes::ERR_TRIAL_DISABLED, null, 422);
         }
 
         $expiresAt = $this->calculateExpiresAt(null, $trialPeriod->getDurationMonths());