Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database

backend/app/Controllers/AuthController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AUTHENTICATION & IDENTITY CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: AuthController.php
+ * الهدف المعماري:
+ * إدارة منظومة الهوية الرقمية والدخول الآمن والتحقق عبر الواتساب (OTP) في منصة صَقِل.
+ * يتولى هذا الملف المهام التالية:
+ * 1. إرسال رموز التحقق لمرة واحدة (OTP) عبر الواتساب بواسطة بوابة نبّه الرسمية (Nabeh Gateway).
+ * 2. التحقق من صحة الرمز وتوليد رموز JWT المشفرة بصلاحيات محددة (طالب، معلم، ولي أمر، مدير).
+ * 3. حماية الحسابات من هجمات الاختراق عبر بصمة الجهاز الرقمية (Device Fingerprinting).
+ * 4. إدارة جلسات تسجيل الدخول والخروج والتحقق من صلاحية التوكن (Token Introspection).
+ * 5. التحقق عبر الرقم الوطني لطلاب مديرية الثقافة العسكرية والمدارس الحكومية.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\NabehService;
 class AuthController
 {
     /**
-     * Request OTP via WhatsApp (Nabeh Gateway)
+     * طلب رمز تحقق OTP جديد وإرساله عبر الواتساب بواسطة بوابة نبّه
      * POST /api/auth/otp/request
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على رقم الهاتف بصيغة دولية أو محلية
+     * @param Response $response كائن الاستجابة بحالة الإرسال وزمن انتهاء الصلاحية
      */
     public function requestOtp(Request $request, Response $response): void
     {