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

apps/student_app/lib/logic/cubits/exam_cubit.dart

@@ -1,15 +1,31 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - ADAPTIVE EXAM STATE MANAGEMENT (CUBIT)
+/// ==============================================================================
+/// 
+/// ملف: exam_cubit.dart
+/// الهدف المعماري:
+/// إدارة حالة دورة حياة الامتحانات التكيفية والتشخيص الذكي في تطبيق الطالب:
+/// 1. جلب الامتحانات مباشرة من واجهات السيرفر (Pure API-Driven) دون أي بيانات أو أسئلة محلية ثابتة.
+/// 2. إدارة المؤقت التنازلي الذكي ومزامنة الوقت المتبقي.
+/// 3. إدارة التنقل بين الأسئلة وحفظ اختيارات الطالب وتحديد البدائل المحددة.
+/// 4. إرسال الإجابات إلى السيرفر لتصحيحها واستلام تقرير التشخيص السقراطي ومؤشر الجاهزية للتوجيهي.
+library;
+
 import 'dart:async';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import '../../data/models/exam_model.dart';
 import '../../data/repositories/app_repositories.dart';
 
+/// الحالات العامة للامتحان
 abstract class ExamState {}
 
+/// الحالة المبدئية قبل بدء التحميل
 class ExamInitial extends ExamState {}
 
+/// حالة انتظار جلب الأسئلة من السيرفر
 class ExamLoading extends ExamState {
   final String message;
-  ExamLoading({this.message = 'جاري تحضير الامتحان والأسئلة التكيفية...'});
+  ExamLoading({this.message = 'جاري تحضير الامتحان والأسئلة التكيفية من السيرفر...'});
 }
 
 class ExamLoaded extends ExamState {

apps/student_app/lib/main.dart

@@ -1,3 +1,16 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - FLUTTER APPLICATION ENTRY POINT
+/// ==============================================================================
+/// 
+/// ملف: main.dart
+/// الهدف المعماري:
+/// نقطة الدخول الرئيسية لتطبيق الطالب الموحد لمنصة صَقِل.
+/// يتولى هذا الملف:
+/// 1. تهيئة بيئة تشغيل فلاتر وتثبيت معايير التصميم العالمي (Cupertino Dark Aesthetic).
+/// 2. حقن وإدارة كافة الـ BLoC/Cubit Providers (المصادقة، المنهاج، المشغل، لوحة الطالب وولي الأمر).
+/// 3. التوجيه التلقائي بين شاشة تسجيل الدخول والشاشة الموحدة وفق حالة الجلسة.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'core/config/app_config.dart';
@@ -10,11 +23,13 @@ import 'logic/cubits/video_playback_cubit.dart';
 import 'presentation/screens/auth/auth_screen.dart';
 import 'presentation/screens/home/unified_home_screen.dart';
 
+/// نقطة انطلاق التطبيق الرئيسية
 void main() {
   WidgetsFlutterBinding.ensureInitialized();
   runApp(const SaqelAppRoot());
 }
 
+/// الودجت الجذرية للتطبيق (Root Widget) المحتوية على المزودات وإعدادات الثيم والاتجاه العربي
 class SaqelAppRoot extends StatefulWidget {
   const SaqelAppRoot({super.key});
 

apps/student_app/lib/presentation/screens/curriculum/curriculum_document_viewer_screen.dart

@@ -1,9 +1,23 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - IN-APP CURRICULUM DOCUMENT & TEXTBOOK READER
+/// ==============================================================================
+/// 
+/// ملف: curriculum_document_viewer_screen.dart
+/// الهدف المعماري:
+/// عارض وقارئ المستندات وأوراق العمل والكتب المدرسية المقررة داخل التطبيق مباشرة:
+/// 1. قراءة سلسة ومريحة للمحتوى دون الحاجة للتحميل والتطبيقات الخارجية.
+/// 2. التحكم اللحظي بحجم الخط (Font Zoom Control +/-).
+/// 3. عرض مهيكل للنتاجات، القواعد الذهبية، الأمثلة الوزارية المحلولة خطوة بخطوة.
+/// 4. تمارين تفاعلية للتقييم الذاتي مع زر لمسي لإظهار وإخفاء الحل النموذجي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
 import '../../../core/utils/saqel_toast.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// شاشة عارض أوراق العمل والملخصات والكتب الوزارية التفاعلية
 class CurriculumDocumentViewerScreen extends StatefulWidget {
   final String title;
   final String documentType; // 'worksheet', 'summary', 'textbook'

apps/student_app/lib/presentation/screens/curriculum/subject_hub_screen.dart

@@ -1,3 +1,16 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SUBJECT HUB & MULTI-TEACHER CURRICULUM SCREEN
+/// ==============================================================================
+/// 
+/// ملف: subject_hub_screen.dart
+/// الهدف المعماري:
+/// المركز الشامل للمادة الدراسية (Subject Hub):
+/// 1. فهرسة وحدات ودروس المنهاج الوزاري وشروحات المعلمين والذكاء الاصطناعي.
+/// 2. بطاقة اختيار الشرح متعدد المعلمين (Multi-Teacher & Saqel AI Video Selector Modal).
+/// 3. مركز بنك الأسئلة والامتحانات التكيفية لبدء الاختبارات الشاملة (Adaptive Exams).
+/// 4. تبويب المذكرات وأوراق العمل والكتب المدرسية المقررة للقراءة والتصفح المباشر.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
@@ -9,6 +22,7 @@ import '../player/socratic_video_player_screen.dart';
 import '../exams/adaptive_exam_screen.dart';
 import 'curriculum_document_viewer_screen.dart';
 
+/// الشاشة المركزية للمادة الدراسية وبوابات الدروس والامتحانات والمصادر
 class SubjectHubScreen extends StatefulWidget {
   final SubjectModel subject;
 

apps/student_app/lib/presentation/screens/exams/adaptive_exam_screen.dart

@@ -1,3 +1,17 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - ADAPTIVE EXAM SCREEN (CUPERTINO LUXURY UI)
+/// ==============================================================================
+/// 
+/// ملف: adaptive_exam_screen.dart
+/// الهدف المعماري:
+/// شاشة تقديم الامتحانات التكيفية بتصميم أبل كوبرتينو المظلم (Dark OLED Aesthetic):
+/// 1. مؤشر تقدم تفاعلي متزامن مع نسبة الإجابات المكتملة.
+/// 2. مؤقت تنازلي ذكي يتغير لونه إلى الأحمر عند اقتراب انتهاء الوقت.
+/// 3. بطاقات أسئلة لمسية فاخرة مع أزرار اختيار مشعة (Glowing Glassmorphic Radios).
+/// 4. شاشة عرض نتائج متقدمة تحتوي على: نسبة الإتقان، وسام الاجتياز، تقرير التشخيص بالذكاء الاصطناعي،
+///    وسوم نقاط الضعف، ومؤشر الجاهزية لامتحان التوجيهي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
@@ -7,6 +21,7 @@ import '../../../core/utils/saqel_toast.dart';
 import '../../../logic/cubits/exam_cubit.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// الشاشة التكيفية لتقديم الامتحان واستقبال نتائج التصحيح اللحظية
 class AdaptiveExamScreen extends StatelessWidget {
   final int examId;
   final String title;

apps/student_app/lib/presentation/screens/player/socratic_video_player_screen.dart

@@ -1,3 +1,18 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SOCRATIC VIDEO PLAYER SCREEN
+/// ==============================================================================
+/// 
+/// ملف: socratic_video_player_screen.dart
+/// الهدف المعماري:
+/// مشغل الفيديو السقراطي الذكي والمحمي في تطبيق صَقِل:
+/// 1. تشغيل الفيديو الرقمي وبث HLS عبر مشغل مخصص عالي الأداء.
+/// 2. حماية الملكية الفكرية بعلامة مائية متحركة ديناميكية (Dynamic Anti-Piracy Watermark).
+/// 3. محاذاة نقاط التقدم اللمسية مع نقاط الفحص السقراطي الزمني (Socratic Checkpoints).
+/// 4. تجميد الفيديو وإظهار نافذة الفحص السقراطي عند وصول المؤشر لنقطة الفحص.
+/// 5. تفعيل الإرجاع العلاجي (Rewind Remediation) عند الإجابة الخاطئة لترسيخ الفهم.
+/// 6. إبراز شارة المعلم المختار (شرح الذكاء الاصطناعي أو المعلم المعتمد).
+library;
+
 import 'dart:async';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
@@ -12,6 +27,7 @@ import '../../widgets/luxury_widgets.dart';
 import '../../widgets/socratic_dialog.dart';
 import 'package:video_player/video_player.dart';
 
+/// مشغل الفيديو السقراطي الذكي ونقاط الفحص والإرجاع العلاجي
 class SocraticVideoPlayerScreen extends StatefulWidget {
   final CurriculumLessonItemModel lesson;
   final SubjectModel? subject;