Add piece-meal queries doc

[luanpotter]

Talk about:

• passing query objects around for piece-meal construction
• what types and generics to use (Base*, *Where, *Join, etc)
• talk more in depth about join refs, re-using joins vs creating new ones

[neel-faire]

One example that would be useful to document a best-practice for is how to use helper functions that have joins:

object BookLoanQueries {

    /**
     * Get all patrons who borrowed books by a specific author within a time range.
     */
    fun getPatronsWhoBorrowedFromAuthor(
        session: ReadSession,
        authorToken: Token<AUTHOR>,
        startTime: DateTime? = null,
        endTime: DateTime? = null,
    ): List<Token<PATRON>> {
        return getLoansByAuthorBaseCriteria(
            session = session,
            authorToken = authorToken,
            startTime = startTime,
            endTime = endTime,
        )
            // Project a field from the joined "book" entity
            .distinctProjectionProperty<Token<PATRON>>("book.borrowerToken")
            .list()
    }

    /**
     * Base criteria builder - creates the join and applies common filters.
     */
    private fun getLoansByAuthorBaseCriteria(
        session: ReadSession,
        authorToken: Token<AUTHOR>,
        startTime: DateTime? = null,
        endTime: DateTime? = null,
    ): TypedCriteria<DbLoanRecord> {
        return session.createCriteria<DbLoanRecord>()
            .createAlias("book", "book")  // Join to book entity
            .addEq("book.authorToken", authorToken)
            .addEq("status", LoanStatus.RETURNED)
            .applyIfNotNull(startTime) {
                addGe("book.checkedOutAt", startTime!!)
            }
            .applyIfNotNull(endTime) {
                addLe("book.checkedOutAt", endTime!!)
            }
    }
}