Summary

Document the ORM (Object-Relational Mapping) framework in database_system, including the entity definition system, table/field mapping macros, and query generation.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

database_system includes a C++ ORM framework at database/orm/entity.h with ENTITY_TABLE and ENTITY_FIELD macros for declarative entity-to-table mapping. This is a significant feature that makes the database system much more usable, but it has no documentation whatsoever.

Source files:

• database/orm/entity.h — Entity base class and mapping macros
• database/orm/entity.cpp — Implementation

ORM frameworks are notoriously difficult to use without proper documentation because they rely on conventions and macro magic that isn't discoverable through code completion alone.

Scope (What)

Create docs/ORM_GUIDE.md covering:

1. ORM Overview

• Design philosophy (Active Record vs Data Mapper pattern)
• Supported database backends for ORM operations
• Limitations and when to use raw SQL instead

2. Entity Definition

// Document the exact macro syntax and usage
class User : public Entity {
    ENTITY_TABLE("users")
    ENTITY_FIELD(int, id, "id", PrimaryKey)
    ENTITY_FIELD(std::string, name, "user_name")
    ENTITY_FIELD(std::string, email, "email", Unique)
    // ... document all supported field options
};

3. ENTITY_TABLE Macro

• Syntax and parameters
• Table naming conventions
• Schema specification support

4. ENTITY_FIELD Macro

• Syntax: ENTITY_FIELD(type, member_name, column_name, ...attributes)
• Supported C++ types and their SQL mappings
• Field attributes (PrimaryKey, Unique, NotNull, Default, etc.)
• Nullable fields handling
• Custom type converters

5. CRUD Operations

• Create (INSERT) examples
• Read (SELECT) with filtering
• Update with partial field sets
• Delete with conditions

6. Query Building

• Programmatic query construction
• Where clause building
• Join support (if any)
• Order by, limit, offset

7. Migration Support

• Schema generation from entity definitions
• Migration strategy (auto-create, manual, etc.)

Acceptance Criteria

• docs/ORM_GUIDE.md created
• All macros documented with exact syntax
• Supported types and attributes listed
• CRUD operation examples provided
• Query building patterns documented
• At least 2 complete entity definition examples
• Limitations clearly stated